Créer un notebook avec Quarto: principes, fonctionnalités

SAGEO, 2023 - Québec, Canada

Nicolas Lambert, Timothée Giraud, Matthieu Viry, Ronan Ysebaert

07 Jun 2023

Evolution des pratiques en SHS (FR)


Avant 2011 : des “black-boxes” méthodologiques

Logiciels payants, ruptures logicielles dans les chaines de traitements, stockage et partage des données et méthodes non optimisé, univers “clic-bouton”.

Evolution des pratiques en SHS (FR)


2011 - récemment : vers des chaines de traitement intégrées

Solutions open source, gratuites, qui couvrent l’ensemble de la chaîne de traitement de l’information, univers de programmation.

Une pratique qui tend aujourd’hui à s’universaliser au sein de la communauté (formation, enseignement, recherche).

Evolution des pratiques en SHS (FR)


Depuis peu… : vers l’ouverture à de nouveaux langages ?

Usage de langages de développement variés en fonction des usages désirés (performence de certaines libs, interactivité, …) et des échanges interdisciplinaires (dataviz).

Comment passer d’un langage à l’autre dans des mêmes chaînes de traitement ?

Evolution des pratiques en SHS (FR)

La réplication en question

  • Où sont stockées les données ?
  • Sur quoi reposent ces protocoles méthodologiques ?
  • Comment les documenter ?
  • Comment les restituer / mettre à jour / adapter ?
Qui pour reprendre ces programmes ?


Qui pour comprendre ce code et ses intentions ?

Recherche reproductible

Ouverture des protocoles de recherche dans l’objectif de confirmer et rendre répétable des résultats de recherche.

  • Disponibilité des données et du code, exécutable.
  • Documentation de l’environnement logiciel nécessaire à son exécution.
  • Transparence dans la collecte de données, ses traitements, analyses et sorties graphiques.
  • Réutilisable par d’autres : documentation du code, de ce qu’il produit et dans quel but.
  • Ouvert aux retours, commentaires, suggestions, critiques, révisions.

Jon Claerbout (sismologue, Univ. Stanford). Il utilise avec son groupe pour la première fois le terme de “recherche reproductible” lors du congrès de la Society of Exploration Geophysics en 1992.

Programmation lettrée & notebooks

Paradigme de programmation (Knuth, 1984) qui consiste à associer code source (pour les ordinateurs) et documentation (pour les humains).

  • Donner les informations suffisantes pour répliquer l’expérimentation, à la manière d’un essai.
  • Vérifier que les conclusions sont valides.
  • Améliorer les programmes / rendre les mauvaises décisions de conception plus évidentes.
  • Utile pour reprendre les programmes ultérieurement.
  • Transmettre et partager les connaissances sous des formes appropriées (tutoriels, manuels).

Un gain général en reproductibilité de la démarche et en ouverture des méthodes scientifiques.

Donald Knuth (mathématicien, Univ. Stanford). Pose les bases de la programmation lettrée dans un premier environnement de literate programming : le WEB qui combine du Pascal et du TeX, appliqué aux nombres premiers (1984).

Notebooks : Principes fondamentaux

Le Notebook est une solution opérationnelle et adaptée pour arriver à ces fins

Source : Pecout, 2022

Les Notebooks du moment

Source : Pecout, 2022

Quarto ?

Un des derniers nés des notebooks (2022)

  • Open-source, basé sur Pandoc.
  • Moins dépendant de R : pas d’installation de packages R, comme c’était le cas avec R Markdown.
  • Peut fonctionner ailleurs que dans l’IDE RStudio : pas d’utilisation exclusive de Knitr (Jupyter, Observable également).
  • Permet d’exécuter différents langages de programmation : R, Python, Julia ou JavaScript (interactivité ++).
  • Possibilité de mises en page customisées avancées (templates ++)

Des sorties multiples




Restituer des analyses reproductibles menées lors d’un projet.

Sortie (site Web) // Dépôt GitLab




Générer des présentations interactives (iframe, animations, slides interactifs) avec le format revealjs.

Exemple : Sortie (Présentation) // Dépôt GitHub // Code




Créer des raports interactifs combinant (éventuellement) plusieurs langages de programmation.

Sortie (Rapport interactif) // Dépôt GitHub // Code (Quarto)




Créer des manuels ou des sections pédagogiques collaboratifs au format Book.

Sortie (Book) // Dépôt GitHub






Soumettre des publications suivant les prérequis (adaptation template LaTeX) de plusieurs revues de référence (Public Library of Science, Elsevier, JSS, etc.)

Journal Articles (Quarto doc)

Squelette d’un notebook (Quarto)





Source : Pecout, 2022

Initier un document Quarto dans RStudio

RStudio propose plusieurs modèles pour initier aisément un notebook.

Initier un document Quarto dans RStudio

RStudio propose plusieurs modèles pour initier aisément un notebook.

Paramétrer son document grâce au YAML

Le YAML permet de définir :

  • Le format de sortie désiré : HTML, PDF (installation d’une distribution TeX requise), .docx.

  • Le type de document souhaité (Document, Présentation, Site Web, etc.)

Il est hautement paramétrable :

  • des paramétrages généraux (choisir un thème, définir une feuille de style css)
  • la table des matières (toc)
  • la numérotation des parties du document
  • les typographies utilisées
  • le choix des couleurs
  • l’affichage des blocs de code
  • l’exécution du code (afficher le code ou non, des messages d’erreur, etc.)
  • le dimensionnement des figures et tables
  • la gestion des urls
  • le paramétrage de la bibliographie
  • l’affichage des notes de bas de page
  • les métadonnées associées au document…

Les possibilités offertes sont présentées dans la documentation Quarto

Paramétrer son document grâce au YAML

Le YAML utilisé pour cette présentation

---
title: "Créer un notebook avec Quarto: principes, fonctionnalités"
subtitle: "SAGEO, 2023 - Québec, Canada"
author: "Nicolas Lambert, Timothée Giraud,  Matthieu Viry, Ronan Ysebaert"
date: 06/7/2023
date-format: "DD MMM YYYY"
title-slide-attributes:
  data-background-color: black
  data-background-image: fig/SAGEO.png
  data-background-size: cover
  data-background-opacity: "0.5"
format:
  revealjs:
    margin: 0
    embed-resources: true
    smaller: true
    scrollable: true
    theme: [simple, custom.scss]
    code-line-numbers: false
editor: visual
execute:
  echo: true
---

Décrire simplement son cheminement grâce à au markdown

  • Langage de balisage léger

  • h1, h2, h3 bold, italic import figure

  • Callout blocks

Paramétrer ses blocs de code grâce aux chunks

  • possibilité d’intégrer du code Python, R, Julia, Observable JS au sein du même document.

  • echo, eval, warning, message, cache, fig.height

  • possibilité de le spécifier dans le YAML (execute:)…

  • ou directement dans les chunks

Ressources pour aller plus loin

Supports utiles

Enjeux de la reproductibilité

A vous de jouer !

[To do] : Initier un document Quarto

  • Créer un modèle Quarto avec RStudio
  • Jouer avec les métadonnées pour paramétrer le document (nom de l’auteur, ajout table des matières, etc.)